Inside Macintosh: QuickDraw GX Objects /

Chapter 5 - Ink Objects / Ink Objects Reference

Functions / Manipulating Ink Object Properties

GXGetInkTags

You can use the GXGetInkTags function to examine one or more of the tag objects associated with an ink object.

long GXGetInkTags(gxInk source, long tagType, long index, 
                long count, gxTag items[]);

source

A reference to the ink object whose tag list you want to examine.

tagType

The type of tag object to search for. A value of 0 indicates that you want to look for all tag types.

index

The (1-based) index of the first such tag reference to return.

count

The number of tag references to return.

items

An array to hold the returned tag references.

function result

The number of tag references found that fit the criteria.

DESCRIPTION

The GXGetInkTags function searches the tag list of the source ink object for references to tag objects with the tag type specified by the tagType parameter. If you specify 0 for the tagType parameter, the GXGetInkTags function searches all tag types.

You can use the index and the count parameters to specify which tag references of the appropriate type the GXGetInkTags function should return. The index parameter indicates the first tag reference to return and the count parameter indicates how many tag references to return. The index parameter must be greater than 0. The count parameter must be greater than 0 or equal to the gxSelectToEnd constant (-1), which indicates that all tag references (starting with the tag reference indicated by the index parameter) should be returned.

The function result is the number of tag references found that fit the criteria. If you pass a value other than nil for the items parameter, the GXGetInkTags function returns in the items parameter the tag references that were found.

Typically, you call this function once with a nil value for the items parameter to determine the number of matching tag references. Then you allocate an appropriately sized array and call the function a second time to obtain the references themselves.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
ink_is_nil
index_is_less_than_one	(debugging version)
count_is_less_than_one	(debugging version)
Warnings
index_out_of_range
count_out_of_range

SEE ALSO

Tag objects are discussed in the chapter "Tag Objects" in this book.

To change the set of tag references associated with an ink, use the GXSetInkTags function, described in the next section.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help